<?php
/** Used by Rho_DB, no need to manually include this file.
*
* @see Rho_DB::factory()
* @package Rho
* @subpackage Rho-database */

/** Interface for database drivers.
* @package Rho
* @subpackage Rho-database */
interface Rho_DB_Driver{
  
  /** Connects to the database.
  * @throws DB_Connection_Exception If there's a connection error.*/
  public function connect();
  
  /** Executes a SQL statement.
  * Will attempt to connect if not already connected to the server.
  * @param string &$sql
  * @return resource|object|bool The result of the query or FALSE
  * @throws Rho_Exception if there's a database error.
  * @throws DB_Connection_Exception If there's a connection error.*/
  public function query(& $sql);
  
  /** Return the number of affected rows.
  * May well not be dependant on $resource - should be called imediately after query().
  * May require an active connection.
  * @param resource|object &$resource The result as returned by query()
  * @return int|bool The number of affected rows (which may be 0) or FALSE if there's no connection.
  * @throws Rho_Exception if there's a database error.
  * @throws DB_Connection_Exception If there's a connection error.*/
  public function affectedRows(& $resource);
  
  /** Frees a result.
  * Should not throw an exception  
  * @param resource|object &$resource The result as returned by query()
  * @return bool TRUE on success.*/
  public function freeResult(& $resource);
  
  /** Return number of rows of a SELECT query result.
  * @param resource|object &$resource The result as returned by query() with a SELECT statement.
  * @return int The number of affected rows (which may be 0).
  * @throws Rho_Exception if there's a database error.*/
  public function numRows(& $resource);
  
  /** Return a row as an object.
  * @param resource|object &$resource The result as returned by query() with a SELECT statement.
  * @param string &$record_class The name of Class of the object returned - normally 'DB_Record'.
  * @param DB_Model &$model A model object responsible for the row object, 
  * passed as a parameter to the record class constructor, or NULL when no model is being used.
  * @return DB_Record Object or NULL.
  * @throws Rho_Exception if there's a database error.*/
  public function fetchObject(& $resource, & $record_class, & $model);

  /** Move the database pointer.
  * This assumes that the first row is 0 - the driver must compansate internally if this is not the case.
  * @param resource|object &$resource The result as returned by query() with a SELECT statement.
  * @param int $row_number The row number to seek to, where 0 is the first row.
  * @return bool TRUE on success  
  * @throws Rho_Exception if there's a database error.*/
  public function seek(& $resource, $row_number);
  
  /** Returns the link to the server if connected.
  * @return resource|object|bool The link, or FALSE if connection failed, or NULL if not currently connected.*/
  public function & getLink();
  
  /** Get the last insert id after an INSERT on a table with an autoincrementing primary key.
  * May well not be dependant on $resource - should be called imediately after query().
  * May require an active connection.
  * @param resource|object &$resource The result as returned by query() with a SELECT statement.
  * @return int|string The last insert id.
  * @throws Rho_Exception if there's a database error.
  * @throws DB_Connection_Exception If there's a connection error.*/
  public function lastInsertID(& $resource);
  
  /** Cleans a string returned from the database.
  * Should reverse escapeString().
  * @internal stripslashes($str) is often sufficient.
  * @param string &$str Note this is passed by reference, so the original variable will be altered.
  * @see escapeString()*/
  public function cleanString(& $str);
  
  /** Converts a date from the database's native format to ISO 8601 format - Y-m-d  .
  * @param string $date Note this is passed by reference, so the original variable will be altered.
  * @see escapeDate() */
  public function convertDate(& $date);
  
  /** Converts a time from the database's native format to ISO 8601 format HH:MM:SS.
  * @param string $time Note this is passed by reference, so the original variable will be altered.
  * @see escapeTime() */
  public function convertTime(& $time);

  /** Converts a date-time from the database's native format to ISO 8601 format.
  * @param string $date Note this is passed by reference, so the original variable will be altered.
  * @return string $date in Y-m-d HH:MM:SS format.
  * @see escapeDateTime() */  
  public function convertDateTime(& $date);
  
  /** Escape a string for use for the database, including adding quotes.
  * @param &$str The string to escape.
  * Note this is passed by reference, so the original variable will be altered.
  * @see cleanString() */
  public function escapeString(& $str);
  
  /** Escape a date for use for the database, including adding quotes if needed.
  * Drivers must convert from the ISO 8601 format to the native format if required.
  * May require an active connection to the database server.
  * @param &$date The string to escape in Y-m-d format
  * Note this is passed by reference, so the original variable will be altered.
  * @see convertDate()
  * @throws Rho_Exception if there's a database error.
  * @throws DB_Connection_Exception If there's a connection error.*/
  public function escapeDate(& $date);
  
  /** Escape a time for use for the database, including adding quotes if needed.
  * Drivers must convert from the ISO 8601 format to the native format if required.
  * @param &$time The string to escape in HH:MM:SS format.
  * Note this is passed by reference, so the original variable will be altered.
  * @see convertTime() */
  public function escapeTime(& $time);
  
  /** Escape a date for use for the database, including adding quotes if needed.
  * Drivers must convert from the ISO 8601 format to the native format if required.
  * @param &$date The string to escape in Y-m-d HH:MM:SS format.
  * Note this is passed by reference, so the original variable will be altered.
  * @see convertDateTime() */  
  public function escapeDateTime(& $date);
  
  /** Escapes a field name for use in the database
  * @param string &$field The field name - may be *.
  * @param string &$table The name of the field's table or an empty string.
  * @return string The escaped field name, e.g. `widgets`.`name`*/
  public function escapeField(& $field, & $table);
  
  /** Escapes a table name for use in the database
  * @param string &$table The name of the table.
  * @return string The escaped table name, e.g. `widgets` */
  public function escapeTable(& $table);
  
  /** Produces a LIMIT snippet for use in an SQL query.
  * @param int $qty The maximum number of records the fetch inclusive.
  * @param int $offset The row number of the first record to fetch from where the first row is 0.
  * Driver must compansate internally if this is not the case.
  * @return string The limit statement, inluding the keyword. e.g. ' LIMIT 20,10 ' */
  public function limit($qty, $offset=NULL);
  
  /** Closes the connection if connected.
  /* Note subsequent calls to the driver, such as query may (and should) re-establish the connection.*/
  public function close();
}